home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / include / content / nsIContent.h < prev    next >
C/C++ Source or Header  |  2006-05-08  |  27KB  |  730 lines
  1. /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is Mozilla Communicator client code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37. #ifndef nsIContent_h___
  38. #define nsIContent_h___
  39.  
  40. #include <stdio.h>
  41. #include "nsCOMPtr.h"
  42. #include "nsISupports.h"
  43. #include "nsEvent.h"
  44. #include "nsAString.h"
  45. #include "nsContentErrors.h"
  46. #include "nsPropertyTable.h"
  47.  
  48. // Forward declarations
  49. class nsIAtom;
  50. class nsIDocument;
  51. class nsPresContext;
  52. class nsVoidArray;
  53. class nsIDOMEvent;
  54. class nsIContent;
  55. class nsISupportsArray;
  56. class nsIDOMRange;
  57. class nsINodeInfo;
  58. class nsIEventListenerManager;
  59. class nsIURI;
  60.  
  61. // IID for the nsIContent interface
  62. #define NS_ICONTENT_IID       \
  63. { 0x3fecc374, 0x2839, 0x4db3, \
  64.  { 0x8d, 0xe8, 0x6b, 0x76, 0xd1, 0xd8, 0xe6, 0xf6 } }
  65.  
  66. /**
  67.  * A node of content in a document's content model. This interface
  68.  * is supported by all content objects.
  69.  */
  70. class nsIContent : public nsISupports {
  71. public:
  72.   NS_DEFINE_STATIC_IID_ACCESSOR(NS_ICONTENT_IID)
  73.  
  74.   nsIContent()
  75.     : mParentPtrBits(0) { }
  76.  
  77.   /**
  78.    * DEPRECATED - Use GetCurrentDoc or GetOwnerDoc.
  79.    * Get the document for this content.
  80.    * @return the document
  81.    */
  82.   virtual nsIDocument* GetDocument() const = 0;
  83.  
  84.   /**
  85.    * Bind this content node to a tree.  If this method throws, the caller must
  86.    * call UnbindFromTree() on the node.  In the typical case of a node being
  87.    * appended to a parent, this will be called after the node has been added to
  88.    * the parent's child list and before nsIDocumentObserver notifications for
  89.    * the addition are dispatched.
  90.    * @param aDocument The new document for the content node.  Must match the
  91.    *                  current document of aParent, if aParent is not null.
  92.    *                  May not be null if aParent is null.
  93.    * @param aParent The new parent for the content node.  May be null if the
  94.    *                node is being bound as a direct child of the document.
  95.    * @param aBindingParent The new binding parent for the content node.
  96.    *                       This is allowed to be null.  In that case, the
  97.    *                       binding parent of aParent, if any, will be used.
  98.    * @param aCompileEventHandlers whether to initialize the event handlers in
  99.    *        the document (used by nsXULElement)
  100.    * @note either aDocument or aParent must be non-null.  If both are null,
  101.    *       this method _will_ crash.
  102.    * @note This method must not be called by consumers of nsIContent on a node
  103.    *       that is already bound to a tree.  Call UnbindFromTree first.
  104.    * @note This method will handle rebinding descendants appropriately (eg
  105.    *       changing their binding parent as needed).
  106.    * @note This method does not add the content node to aParent's child list
  107.    * @throws NS_ERROR_OUT_OF_MEMORY if that happens
  108.    */
  109.   virtual nsresult BindToTree(nsIDocument* aDocument, nsIContent* aParent,
  110.                               nsIContent* aBindingParent,
  111.                               PRBool aCompileEventHandlers) = 0;
  112.  
  113.   /**
  114.    * Unbind this content node from a tree.  This will set its current document
  115.    * and binding parent to null.  In the typical case of a node being removed
  116.    * from a parent, this will be called after it has been removed from the
  117.    * parent's child list and after the nsIDocumentObserver notifications for
  118.    * the removal have been dispatched.   
  119.    * @param aDeep Whether to recursively unbind the entire subtree rooted at
  120.    *        this node.  The only time PR_FALSE should be passed is when the
  121.    *        parent node of the content is being destroyed.
  122.    * @param aNullParent Whether to null out the parent pointer as well.  This
  123.    *        is usually desirable.  This argument should only be false while
  124.    *        recursively calling UnbindFromTree when a subtree is detached.
  125.    * @note This method is safe to call on nodes that are not bound to a tree.
  126.    */
  127.   virtual void UnbindFromTree(PRBool aDeep = PR_TRUE,
  128.                               PRBool aNullParent = PR_TRUE) = 0;
  129.   
  130.   /**
  131.    * Returns true if the content has an ancestor that is a document.
  132.    *
  133.    * @return whether this content is in a document tree
  134.    */
  135.   virtual PRBool IsInDoc() const = 0;
  136.  
  137.   /**
  138.    * Get the document that this content is currently in, if any. This will be
  139.    * null if the content has no ancestor that is a document.
  140.    *
  141.    * @return the current document
  142.    */
  143.   nsIDocument *GetCurrentDoc() const
  144.   {
  145.     // XXX This should become:
  146.     // return IsInDoc() ? GetOwnerDoc() : nsnull;
  147.     return GetDocument();
  148.   }
  149.  
  150.   /**
  151.    * Get the ownerDocument for this content.
  152.    *
  153.    * @return the ownerDocument
  154.    */
  155.   virtual nsIDocument *GetOwnerDoc() const = 0;
  156.  
  157.   /**
  158.    * Get the parent content for this content.
  159.    * @return the parent, or null if no parent
  160.    */
  161.   nsIContent* GetParent() const
  162.   {
  163.     return NS_REINTERPRET_CAST(nsIContent *, mParentPtrBits & ~kParentBitMask);
  164.   }
  165.  
  166.   /**
  167.    * Get whether this content is C++-generated anonymous content
  168.    * @see nsIAnonymousContentCreator
  169.    * @return whether this content is anonymous
  170.    */
  171.   virtual PRBool IsNativeAnonymous() const = 0;
  172.  
  173.   /**
  174.    * Set whether this content is anonymous
  175.    * @see nsIAnonymousContentCreator
  176.    * @param aAnonymous whether this content is anonymous
  177.    */
  178.   virtual void SetNativeAnonymous(PRBool aAnonymous) = 0;
  179.  
  180.   /**
  181.    * Get the namespace that this element's tag is defined in
  182.    * @return the namespace
  183.    */
  184.   virtual PRInt32 GetNameSpaceID() const = 0;
  185.  
  186.   /**
  187.    * Get the tag for this element. This will always return a non-null
  188.    * atom pointer (as implied by the naming of the method).
  189.    */
  190.   virtual nsIAtom *Tag() const = 0;
  191.  
  192.   /**
  193.    * Get the NodeInfo for this element
  194.    * @return the nodes node info
  195.    */
  196.   virtual nsINodeInfo * GetNodeInfo() const = 0;
  197.  
  198.   /**
  199.    * Get the number of children
  200.    * @return the number of children
  201.    */
  202.   virtual PRUint32 GetChildCount() const = 0;
  203.  
  204.   /**
  205.    * Get a child by index
  206.    * @param aIndex the index of the child to get, or null if index out
  207.    *               of bounds
  208.    * @return the child
  209.    */
  210.   virtual nsIContent *GetChildAt(PRUint32 aIndex) const = 0;
  211.  
  212.   /**
  213.    * Get the index of a child within this content
  214.    * @param aPossibleChild the child to get the index
  215.    * @return the index of the child, or -1 if not a child
  216.    */
  217.   virtual PRInt32 IndexOf(nsIContent* aPossibleChild) const = 0;
  218.  
  219.   /**
  220.    * Insert a content node at a particular index.
  221.    *
  222.    * @param aKid the content to insert
  223.    * @param aIndex the index it is being inserted at (the index it will have
  224.    *        after it is inserted)
  225.    * @param aNotify whether to notify the document that the insert has
  226.    *        occurred
  227.    */
  228.   virtual nsresult InsertChildAt(nsIContent* aKid, PRUint32 aIndex,
  229.                                  PRBool aNotify) = 0;
  230.  
  231.   /**
  232.    * Append a content node to the end of the child list.
  233.    *
  234.    * @param aKid the content to append
  235.    * @param aNotify whether to notify the document that the replace has
  236.    *        occurred
  237.    */
  238.   virtual nsresult AppendChildTo(nsIContent* aKid, PRBool aNotify) = 0;
  239.  
  240.   /**
  241.    * Remove a child from this content node.
  242.    *
  243.    * @param aIndex the index of the child to remove
  244.    * @param aNotify whether to notify the document that the replace has
  245.    *        occurred
  246.    */
  247.   virtual nsresult RemoveChildAt(PRUint32 aIndex, PRBool aNotify) = 0;
  248.  
  249.   /**
  250.    * Returns an atom holding the name of the attribute of type ID on
  251.    * this content node (if applicable).  Returns null for non-element
  252.    * content nodes.
  253.    */
  254.   virtual nsIAtom *GetIDAttributeName() const = 0;
  255.  
  256.   /**
  257.    * Normalizes an attribute name and returns it as a nodeinfo if an attribute
  258.    * with that name exists. This method is intended for character case
  259.    * conversion if the content object is case insensitive (e.g. HTML). Returns
  260.    * the nodeinfo of the attribute with the specified name if one exists or
  261.    * null otherwise.
  262.    *
  263.    * @param aStr the unparsed attribute string
  264.    * @return the node info. May be nsnull.
  265.    */
  266.   virtual already_AddRefed<nsINodeInfo> GetExistingAttrNameFromQName(const nsAString& aStr) const = 0;
  267.  
  268.   /**
  269.    * Set attribute values. All attribute values are assumed to have a
  270.    * canonical string representation that can be used for these
  271.    * methods. The SetAttr method is assumed to perform a translation
  272.    * of the canonical form into the underlying content specific
  273.    * form.
  274.    *
  275.    * @param aNameSpaceID the namespace of the attribute
  276.    * @param aName the name of the attribute
  277.    * @param aValue the value to set
  278.    * @param aNotify specifies how whether or not the document should be
  279.    *        notified of the attribute change.
  280.    */
  281.   nsresult SetAttr(PRInt32 aNameSpaceID, nsIAtom* aName,
  282.                    const nsAString& aValue, PRBool aNotify)
  283.   {
  284.     return SetAttr(aNameSpaceID, aName, nsnull, aValue, aNotify);
  285.   }
  286.  
  287.   /**
  288.    * Set attribute values. All attribute values are assumed to have a
  289.    * canonical String representation that can be used for these
  290.    * methods. The SetAttr method is assumed to perform a translation
  291.    * of the canonical form into the underlying content specific
  292.    * form.
  293.    *
  294.    * @param aNameSpaceID the namespace of the attribute
  295.    * @param aName the name of the attribute
  296.    * @param aPrefix the prefix of the attribute
  297.    * @param aValue the value to set
  298.    * @param aNotify specifies how whether or not the document should be
  299.    *        notified of the attribute change.
  300.    */
  301.   virtual nsresult SetAttr(PRInt32 aNameSpaceID, nsIAtom* aName,
  302.                            nsIAtom* aPrefix, const nsAString& aValue,
  303.                            PRBool aNotify) = 0;
  304.  
  305.   /**
  306.    * Get the current value of the attribute. This returns a form that is
  307.    * suitable for passing back into SetAttr.
  308.    *
  309.    * @param aNameSpaceID the namespace of the attr
  310.    * @param aName the name of the attr
  311.    * @param aResult the value (may legitimately be the empty string) [OUT]
  312.    * @throws NS_CONTENT_ATTR_NOT_THERE if the attribute is not set and has no
  313.    *         default value
  314.    * @throws NS_CONTENT_ATTR_NO_VALUE if the attribute exists but has no value
  315.    * @throws NS_CONTENT_ATTR_HAS_VALUE if the attribute exists and has a
  316.    *         non-empty value (==NS_OK)
  317.    */
  318.   virtual nsresult GetAttr(PRInt32 aNameSpaceID, nsIAtom* aName, 
  319.                            nsAString& aResult) const = 0;
  320.  
  321.   /**
  322.    * Determine if an attribute has been set (empty string or otherwise).
  323.    *
  324.    * @param aNameSpaceId the namespace id of the attribute
  325.    * @param aAttr the attribute name
  326.    * @return whether an attribute exists
  327.    */
  328.   virtual PRBool HasAttr(PRInt32 aNameSpaceID, nsIAtom* aName) const = 0;
  329.  
  330.   /**
  331.    * Remove an attribute so that it is no longer explicitly specified.
  332.    *
  333.    * @param aNameSpaceID the namespace id of the attribute
  334.    * @param aAttr the name of the attribute to unset
  335.    * @param aNotify specifies whether or not the document should be
  336.    * notified of the attribute change
  337.    */
  338.   virtual nsresult UnsetAttr(PRInt32 aNameSpaceID, nsIAtom* aAttr, 
  339.                              PRBool aNotify) = 0;
  340.  
  341.  
  342.   /**
  343.    * Get the namespace / name / prefix of a given attribute.
  344.    * 
  345.    * @param aIndex the index of the attribute name
  346.    * @param aNameSpace the name space ID of the attribute name [OUT]
  347.    * @param aName the attribute name [OUT]
  348.    * @param aPrefix the attribute prefix [OUT]
  349.    *
  350.    */
  351.   virtual nsresult GetAttrNameAt(PRUint32 aIndex, PRInt32* aNameSpaceID,
  352.                                  nsIAtom** aName, nsIAtom** aPrefix) const = 0;
  353.  
  354.   /**
  355.    * Get the number of all specified attributes.
  356.    *
  357.    * @return the number of attributes
  358.    */
  359.   virtual PRUint32 GetAttrCount() const = 0;
  360.  
  361.   /**
  362.    * Inform content of range ownership changes.  This allows content
  363.    * to do the right thing to ranges in the face of changes to the content
  364.    * model.
  365.    * RangeRemove -- informs content that it no longer owns a range endpoint
  366.    * GetRangeList -- returns the list of ranges that have one or both endpoints
  367.    *                 within this content item
  368.    */
  369.   /**
  370.    * Inform content that it owns one or both range endpoints
  371.    * @param aRange the range the content owns
  372.    */
  373.   virtual nsresult RangeAdd(nsIDOMRange* aRange) = 0;
  374.  
  375.   /**
  376.    * Inform content that it no longer owns either range endpoint
  377.    * @param aRange the range the content no longer owns
  378.    */
  379.   virtual void RangeRemove(nsIDOMRange* aRange) = 0;
  380.  
  381.   /**
  382.    * Get the list of ranges that have either endpoint in this content
  383.    * item.
  384.    * @return the list of ranges owned partially by this content. The
  385.    * nsVoidArray is owned by the content object and its lifetime is
  386.    * controlled completely by the content object.
  387.    */
  388.   virtual const nsVoidArray *GetRangeList() const = 0;
  389.  
  390.   /**
  391.    * Handle a DOM event for this piece of content.  This method is responsible
  392.    * for handling and controlling all three stages of events, capture, local
  393.    * and bubble.  It also does strange things to anonymous content which whiz
  394.    * right by this author's head.
  395.    *
  396.    * Here are some beginning explanations:
  397.    * - if in INIT or CAPTURE mode, it must pass the event to its parent in
  398.    *   CAPTURE mode (this happens before the event is fired, therefore the
  399.    *   firing of events will occur from the root up to the target).
  400.    * - The event is fired to listeners.
  401.    * - If in INIT or BUBBLE mode, it passes the event to its parent in BUBBLE
  402.    *   mode.  This means that the events will be fired up the chain starting
  403.    *   from the target to the ancestor.
  404.    *
  405.    * NOTE: if you are extending nsGenericElement and have to do a default
  406.    * action, call super::HandleDOMEvent() first and check for
  407.    * aEventStatus != nsEventStatus_eIgnore and make sure you are not in CAPTURE
  408.    * mode before proceeding.
  409.    *
  410.    * XXX Go comment that method, Will Robinson.
  411.    * @param aPresContext the current presentation context
  412.    * @param aEvent the event that is being propagated
  413.    * @param aDOMEvent a special event that may contain a modified target.  Pass
  414.    *        in null here or aDOMEvent if you are in HandleDOMEvent already;
  415.    *        don't worry your pretty little head about it.
  416.    * @param aFlags flags that describe what mode we are in.  Generally
  417.    *        NS_EVENT_FLAG_CAPTURE, NS_EVENT_FLAG_BUBBLE and NS_EVENT_FLAG_INIT
  418.    *        are the ones that matter.
  419.    * @param aEventStatus the status returned from the function.  Generally
  420.    *        nsEventStatus_eIgnore
  421.    */
  422.   virtual nsresult HandleDOMEvent(nsPresContext* aPresContext,
  423.                                   nsEvent* aEvent, nsIDOMEvent** aDOMEvent,
  424.                                   PRUint32 aFlags,
  425.                                   nsEventStatus* aEventStatus) = 0;
  426.  
  427.   /**
  428.    * Get a unique ID for this piece of content.
  429.    * This ID is used as a key to store state information 
  430.    * about this content object and its associated frame object.
  431.    * The state information is stored in a dictionary that is
  432.    * manipulated by the frame manager (nsIFrameManager) inside layout.
  433.    * An opaque pointer to this dictionary is passed to the session
  434.    * history as a handle associated with the current document's state
  435.    *
  436.    * These methods are DEPRECATED, DON'T USE THEM!!!
  437.    *
  438.    */
  439.   virtual PRUint32 ContentID() const = 0;
  440.   /**
  441.    * Set the unique content ID for this content.
  442.    * @param aID the ID to set
  443.    */
  444.   virtual void SetContentID(PRUint32 aID)
  445.   {
  446.   }
  447.  
  448.   /**
  449.    * Set the focus on this content.  This is generally something for the event
  450.    * state manager to do, not ordinary people.  Ordinary people should do
  451.    * something like nsGenericHTMLElement::SetElementFocus().  This method is
  452.    * the end result, the point where the content finds out it has been focused.
  453.    * 
  454.    * All content elements are potentially focusable.
  455.    *
  456.    * @param aPresContext the pres context
  457.    * @see nsGenericHTMLElement::SetElementFocus()
  458.    */
  459.   virtual void SetFocus(nsPresContext* aPresContext)
  460.   {
  461.   }
  462.  
  463.   /**
  464.    * Remove the focus on this content.  This is generally something for the
  465.    * event state manager to do, not ordinary people.  Ordinary people should do
  466.    * something like nsGenericHTMLElement::SetElementFocus().  This method is
  467.    * the end result, the point where the content finds out it has been focused.
  468.    * 
  469.    * All content elements are potentially focusable.
  470.    *
  471.    * @param aPresContext the pres context
  472.    * @see nsGenericHTMLElement::SetElementFocus()
  473.    */
  474.   virtual void RemoveFocus(nsPresContext* aPresContext)
  475.   {
  476.   }
  477.  
  478.   /**
  479.    * Check if this content is focusable and in the current tab order.
  480.    * Note: most callers should use nsIFrame::IsFocusable() instead as it 
  481.    *       checks visibility and other layout factors as well.
  482.    * Tabbable is indicated by a nonnegative tabindex & is a subset of focusable.
  483.    * For example, only the selected radio button in a group is in the 
  484.    * tab order, unless the radio group has no selection in which case
  485.    * all of the visible, non-disabled radio buttons in the group are 
  486.    * in the tab order. On the other hand, all of the visible, non-disabled 
  487.    * radio buttons are always focusable via clicking or script.
  488.    * Also, depending on either the accessibility.tabfocus pref or
  489.    * a system setting (nowadays: Full keyboard access, mac only)
  490.    * some widgets may be focusable but removed from the tab order.
  491.    * @param  [inout, optional] aTabIndex the computed tab index
  492.    *         In: default tabindex for element (-1 nonfocusable, == 0 focusable)
  493.    *         Out: computed tabindex
  494.    * @param  [optional] aTabIndex the computed tab index
  495.    *         < 0 if not tabbable
  496.    *         == 0 if in normal tab order
  497.    *         > 0 can be tabbed to in the order specified by this value
  498.    * @return whether the content is focusable via mouse, kbd or script.
  499.    */
  500.   virtual PRBool IsFocusable(PRInt32 *aTabIndex = nsnull)
  501.   {
  502.     if (aTabIndex) 
  503.       *aTabIndex = -1; // Default, not tabbable
  504.     return PR_FALSE;
  505.   }
  506.  
  507.   /**
  508.    * Gets content node with the binding responsible for our construction (and
  509.    * existence).  Used by anonymous content (XBL-generated). null for all
  510.    * explicit content.
  511.    *
  512.    * @return the binding parent
  513.    */
  514.   virtual nsIContent *GetBindingParent() const = 0;
  515.  
  516.   /**
  517.    * Bit-flags to pass (or'ed together) to IsContentOfType()
  518.    */
  519.   enum {
  520.     /** text elements */
  521.     eTEXT                = 0x00000001,
  522.     /** dom elements */
  523.     eELEMENT             = 0x00000002,
  524.     /** html elements */
  525.     eHTML                = 0x00000004,
  526.     /** form controls */
  527.     eHTML_FORM_CONTROL   = 0x00000008,
  528.     /** XUL elements */
  529.     eXUL                 = 0x00000010,
  530.     /** xml processing instructions */
  531.     ePROCESSING_INSTRUCTION = 0x00000020,
  532.     /** svg elements */
  533.     eSVG                 = 0x00000040,
  534.     /** comment nodes */
  535.     eCOMMENT             = 0x00000080
  536.   };
  537.  
  538.   /**
  539.    * API for doing a quick check if a content object is of a given
  540.    * type, such as HTML, XUL, Text, ...  Use this when you can instead of
  541.    * checking the tag.
  542.    *
  543.    * @param aFlags what types you want to test for (see above, eTEXT, eELEMENT,
  544.    *        eHTML, eHTML_FORM_CONTROL, eXUL)
  545.    * @return whether the content matches ALL flags passed in
  546.    */
  547.   virtual PRBool IsContentOfType(PRUint32 aFlags) const = 0;
  548.  
  549.   /**
  550.    * Get the event listener manager, the guy you talk to to register for events
  551.    * on this element.
  552.    * @param aResult the event listener manager [OUT]
  553.    */
  554.   virtual nsresult GetListenerManager(nsIEventListenerManager** aResult) = 0;
  555.  
  556.   /**
  557.    * Get the base URI for any relative URIs within this piece of
  558.    * content. Generally, this is the document's base URI, but certain
  559.    * content carries a local base for backward compatibility, and XML
  560.    * supports setting a per-node base URI.
  561.    *
  562.    * @return the base URI
  563.    */
  564.   virtual already_AddRefed<nsIURI> GetBaseURI() const = 0;
  565.  
  566.   /**
  567.    * This method is called when the parser finishes creating the element.  This
  568.    * particularly means that it has done everything you would expect it to have
  569.    * done after it encounters the > at the end of the tag (for HTML or XML).
  570.    * This includes setting the attributes, setting the document / form, and
  571.    * placing the element into the tree at its proper place.
  572.    *
  573.    * For container elements, this is called *before* any of the children are
  574.    * created or added into the tree.
  575.    *
  576.    * NOTE: this is currently only called for input and button, in the HTML
  577.    * content sink.  If you want to call it on your element, modify the content
  578.    * sink of your choice to do so.  This is an efficiency measure.
  579.    *
  580.    * If you also need to determine whether the parser is the one creating your
  581.    * element (through createElement() or cloneNode() generally) then add a
  582.    * boolean aFromParser to the NS_NewXXX() constructor for your element and
  583.    * have the parser pass true.  See nsHTMLInputElement.cpp and
  584.    * nsHTMLContentSink::MakeContentObject().
  585.    *
  586.    * DO NOT USE THIS METHOD to get around the fact that it's hard to deal with
  587.    * attributes dynamically.  If you make attributes affect your element from
  588.    * this method, it will only happen on initialization and JavaScript will not
  589.    * be able to create elements (which requires them to first create the
  590.    * element and then call setAttribute() directly, at which point
  591.    * DoneCreatingElement() has already been called and is out of the picture).
  592.    */
  593.   virtual void DoneCreatingElement()
  594.   {
  595.   }
  596.  
  597.   /**
  598.    * Call to let the content node know that it may now have a frame.
  599.    * The content node may use this to determine what MayHaveFrame
  600.    * returns.
  601.    */
  602.   virtual void SetMayHaveFrame(PRBool aMayHaveFrame)
  603.   {
  604.   }
  605.  
  606.   /**
  607.    * Returns PR_TRUE if there is a chance that the content node has a
  608.    * frame, PR_FALSE otherwise.
  609.    */
  610.   virtual PRBool MayHaveFrame() const
  611.   {
  612.     return PR_TRUE;
  613.   }
  614.     
  615.   /**
  616.    * This method is called when the parser begins creating the element's 
  617.    * children, if any are present.
  618.    *
  619.    * This is only called for XTF elements currently.
  620.    */
  621.   virtual void BeginAddingChildren()
  622.   {
  623.   }
  624.  
  625.   /**
  626.    * This method is called when the parser finishes creating the element's children,
  627.    * if any are present.
  628.    *
  629.    * NOTE: this is currently only called for textarea, select, applet, and
  630.    * object elements in the HTML content sink.  If you want
  631.    * to call it on your element, modify the content sink of your
  632.    * choice to do so.  This is an efficiency measure.
  633.    *
  634.    * If you also need to determine whether the parser is the one creating your
  635.    * element (through createElement() or cloneNode() generally) then add a
  636.    * boolean aFromParser to the NS_NewXXX() constructor for your element and
  637.    * have the parser pass true.  See nsHTMLInputElement.cpp and
  638.    * nsHTMLContentSink::MakeContentObject().
  639.    */
  640.   virtual void DoneAddingChildren()
  641.   {
  642.   }
  643.  
  644.   /**
  645.    * For HTML textarea, select, applet, and object elements, returns
  646.    * PR_TRUE if all children have been added OR if the element was not
  647.    * created by the parser. Returns PR_TRUE for all other elements.
  648.    */
  649.   virtual PRBool IsDoneAddingChildren()
  650.   {
  651.     return PR_TRUE;
  652.   }
  653.  
  654.   /**
  655.    * Method to get the _intrinsic_ content state of this content node.  This is
  656.    * the state that is independent of the node's presentation.  To get the full
  657.    * content state, use nsIEventStateManager.  Also see nsIEventStateManager
  658.    * for the possible bits that could be set here.
  659.    */
  660.   // XXXbz this is PRInt32 because all the ESM content state APIs use
  661.   // PRInt32.  We should really use PRUint32 instead.
  662.   virtual PRInt32 IntrinsicState() const
  663.   {
  664.     return 0;
  665.   }
  666.     
  667.  
  668.   /* Methods for manipulating content node properties.  For documentation on
  669.    * properties, see nsPropertyTable.h.
  670.    */
  671.  
  672.   virtual void* GetProperty(nsIAtom  *aPropertyName,
  673.                             nsresult *aStatus = nsnull) const
  674.   { if (aStatus) *aStatus = NS_ERROR_NOT_IMPLEMENTED; return nsnull; }
  675.  
  676.   virtual nsresult SetProperty(nsIAtom                   *aPropertyName,
  677.                                void                      *aValue,
  678.                                NSPropertyDtorFunc         aDtor = nsnull)
  679.   { return NS_ERROR_NOT_IMPLEMENTED; }
  680.  
  681.   virtual nsresult DeleteProperty(nsIAtom *aPropertyName)
  682.   { return NS_ERROR_NOT_IMPLEMENTED; }
  683.  
  684.   virtual void* UnsetProperty(nsIAtom  *aPropertyName,
  685.                               nsresult *aStatus = nsnull)
  686.   { if (aStatus) *aStatus = NS_ERROR_NOT_IMPLEMENTED; return nsnull; }
  687.  
  688.  
  689. #ifdef DEBUG
  690.   /**
  691.    * List the content (and anything it contains) out to the given
  692.    * file stream. Use aIndent as the base indent during formatting.
  693.    * Returns NS_OK unless a file error occurs.
  694.    */
  695.   virtual void List(FILE* out = stdout, PRInt32 aIndent = 0) const = 0;
  696.  
  697.   /**
  698.    * Dump the content (and anything it contains) out to the given
  699.    * file stream. Use aIndent as the base indent during formatting.
  700.    * Returns NS_OK unless a file error occurs.
  701.    */
  702.   virtual void DumpContent(FILE* out = stdout, PRInt32 aIndent = 0,
  703.                            PRBool aDumpAll = PR_TRUE) const = 0;
  704. #endif
  705.  
  706.   enum ETabFocusType {
  707.   //eTabFocus_textControlsMask = (1<<0),  // unused - textboxes always tabbable
  708.     eTabFocus_formElementsMask = (1<<1),  // non-text form elements
  709.     eTabFocus_linksMask = (1<<2),         // links
  710.     eTabFocus_any = 1 + (1<<1) + (1<<2)   // everything that can be focused
  711.   };
  712.  
  713.   // Tab focus model bit field:
  714.   static PRInt32 sTabFocusModel;
  715.  
  716.   // accessibility.tabfocus_applies_to_xul pref - if it is set to true,
  717.   // the tabfocus bit field applies to xul elements.
  718.   static PRBool sTabFocusModelAppliesToXUL;
  719.  
  720. protected:
  721.   typedef PRWord PtrBits;
  722.  
  723.   // Subclasses may use the low two bits of mParentPtrBits to store other data
  724.   enum { kParentBitMask = 0x3 };
  725.  
  726.   PtrBits      mParentPtrBits;
  727. };
  728.  
  729. #endif /* nsIContent_h___ */
  730.